SQL Server 2008 : Defining Server-Side Traces

To start a server-side trace, you need to define the trace by using the trace-related system procedures. These procedures can be called from within a SQL Server stored procedure or batch. You define a server-side trace by using the following four procedures:

• sp_trace_create— This procedure is used to create the trace definition. It sets up the trace and defines the file to store the captured events. sp trace create returns a trace ID number that you need to reference from the other three procedures to further define and manage the trace.

• sp_trace_setevent— You need to call this procedure once for each data column of every event that you want to capture.

• sp_trace_setfilter— You call this procedure once for each filter you want to define on an event data column.

• sp_trace_setstatus— After the trace is defined, you call this procedure to start, stop, or remove the trace. You must stop and remove a trace definition before you can open and view the trace file.

You will find that manually creating procedure scripts for tracing can be rather tedious. Much of the tedium is due to the fact that many numeric parameters drive the trace execution. For example, the sp_trace_setevent procedure accepts an eventid and a columnid that determine what event data will be captured. Fortunately, SQL Server 2008 provides a set of catalog views that contain these numeric values and what they represent. The sys.trace_categories catalog view contains the event categories. The sys.trace_events catalog view contains the trace events, and sys.trace_columns contains the trace columns. The following SELECT statement utilizes two of these system views to return the available events and their related categories:

select e.trace_event_id, e.name 'Event Name', c.name 'Category Name'
 from sys.trace_events e
  join sys.trace_categories c on e.category_id = c.category_id
 order by e.trace_event_id

The results of this SELECT statement are shown in Table 1.

The numeric IDs for the trace columns can be obtained from the sys.trace_columns catalog view, as shown in the following example:

select trace_column_id, name 'Column Name', type_name 'Data Type'
 from sys.trace_columns
 order by trace_column_id

Table 2 shows the results of this SELECT statement and lists all the available trace columns.

You have to call the sp_trace_setevent procedure once for each data column you want captured for each event in the trace. Based on the number of events and number of columns, you can see that this can result in a lot of executions of the sp_trace_setevent procedure for a larger trace definition.

To set up filters, you must pass the column ID, the filter value, and numeric values for the logical operator and column operator to the sp_trace_setfilter procedure. The logical operator can be either 0 or 1. A value of 0 indicates that the specified filter on the column should be ANDed with any other filters on the column, whereas a value of 1 indicates that the OR operator should be applied. Table 3 describes the values allowed for the column operators.

Fortunately, there is an easier way of generating a trace definition script. You can set up your traces by using the SQL Profiler GUI and script the trace definition to a file. After you define the trace and specify the events, data columns, and filters you want to use, you select File, Export, Script Trace Definition. The SQL commands (including calls to the aforementioned system stored procedures) to define the trace, start the trace, and write the trace to a file are generated into one script file. You have the option to generate a script that works with SQL Server 2000, 2005 or 2008. Listing 1 shows an example of a trace definition exported from the Profiler. It contains the trace definitions for the TSQL trace template. You must replace the text InsertFileNameHere with an appropriate filename, prefixed with its pathname, before running this script.

Listing 1. A SQL Script for Creating and Starting a Server-Side Trace

/****************************************************/
/* Created by: SQL Server 2008 Profiler             */
/* Date: 05/10/2009  07:20:54 PM         */
/****************************************************/


-- Create a Queue
declare @rc int
declare @TraceID int
declare @maxfilesize bigint
set @maxfilesize = 5

— Please replace the text InsertFileNameHere, with an appropriate
— filename prefixed by a path, e.g., c:\MyFolder\MyTrace. The .trc extension
— will be appended to the filename automatically. If you are writing from
— remote server to local drive, please use UNC path and make sure server has
— write access to your network share

exec @rc = sp_trace_create @TraceID output, 0, N'InsertFileNameHere', @maxfilesize,
NULL
if (@rc != 0) goto error

— Client side File and Table cannot be scripted

— Set the events
declare @on bit
set @on = 1
exec sp_trace_setevent @TraceID, 10, 2, @on
exec sp_trace_setevent @TraceID, 10, 12, @on
exec sp_trace_setevent @TraceID, 10, 13, @on
exec sp_trace_setevent @TraceID, 12, 1, @on
exec sp_trace_setevent @TraceID, 12, 12, @on
exec sp_trace_setevent @TraceID, 12, 13, @on


— Set the Filters
declare @intfilter int
declare @bigintfilter bigint

— Set the trace status to start
exec sp_trace_setstatus @TraceID, 1

— display trace id for future references
select TraceID=@TraceID
goto finish

error:
select ErrorCode=@rc
finish:




go

				  

Monitoring Running Traces

SQL Server 2008 provides some additional built-in user-defined functions to get information about currently running traces. Like the fn_trace_gettable function discussed previously, these functions return the information as a tabular result. The available functions are as follows:

• fn_trace_getinfo(trace_id)— This function is passed a traceid, and it returns information about the specified trace. If passed the value of default, it returns information about all existing traces. An example of the output from this function is shown in Listing 2.

• fn_trace_geteventinfo(trace_id)— This function returns a list of the events and data columns being captured for the specified trace. Only the event and column ID values are returned. You can use the information provided in Tables 1 and 2 to map the IDs to the more meaningful event names and column names.

• fn_trace_getfilterinfo(trace_id)— This function returns information about the filters being applied to the specified trace. Again, the column ID and logical and comparison operator values are returned as integer IDs that you need to decipher. See Table 3 for a listing of the column operator values.

Listing 2. An Example of Using the Built-in User-Defined Functions for Monitoring Traces

SELECT * FROM ::fn_trace_getinfo(default)


traceid     property    value
----------------------------------------------------------------------
1           1           2
1           2           C:\Program Files\Microsoft SQL Server\MSSQL.1\
                         MSSQL\LOG\log_376.trc
1           3           20
1           4           NULL
1           5           1
2           1           0
2           2           c:\trace\mytrace.trc.trc
2           3           5
2           4           NULL
2           5           1


select * from ::fn_Trace_getfilterinfo(2)

columnid    logical_operator comparison_operator value
-------------------------------------------------------------
3           0                0                   6
10          0                7                   Profiler
10          0                7                   SQLAgent

The output from the functions that return trace information is relatively cryptic because many of the values returned are numeric. For example, the property values returned by fn_trace_getinfo are specified as integer IDs. Table 6.5 describes of each of these property IDs.

Stopping Server-Side Traces

It is important to keep track of the traces you have running and to ensure that “heavy” traces are stopped. Heavy traces are typically traces that capture a lot of events and are run on a busy SQL Server. These traces can affect the overall performance of your SQL Server machine and write a large amount of information to the trace output file. If you specified a stop time when you started the trace, it automatically stops and closes when the stop time is reached. For example, in the SQL script in Listing 6.2, if you wanted the trace to run for 15 minutes instead of indefinitely, you would set the value for the stoptime variable at the beginning of the script, using a command similar to the following:

   set @stoptime = dateadd(minute, 15, getdate())

To otherwise stop a running server-side trace, you use the sp_trace_setstatus stored procedure and pass it the trace ID and a status of 0. Stopping a trace only stops gathering trace information and does not delete the trace definition from SQL Server. Essentially, it pauses the trace. You can restart the trace by passing sp_trace_setstatus a status value of 1.

After you stop a trace, you can close the trace and delete its definition from SQL Server by passing sp_trace_setstatus the ID of the trace you want to stop and a status value of 2. After you close the trace, you must redefine it before you can restart it.

If you don’t know the ID of the trace you want to stop, you can use the fn_trace_getinfo function or the sys.traces catalog view to return a list of all running traces and select the appropriate trace ID. The following example shows how to stop and close a trace with a trace ID of 2:

-- Set the trace status to stop
exec sp_trace_setstatus 2, 0
go

-- Close and Delete the trace
exec sp_trace_setstatus 2, 2
go

If you want to stop and close multiple traces, you must call sp_trace_setstatus twice for each trace. Listing 3 provides an example of a system stored procedure that you can create in SQL Server to stop a specific trace or automatically stop all currently running traces.

Listing 3. A Sample System Stored Procedure to Stop Profiler Traces

use master
go
if object_id ('sp_stop_profiler_trace') is not null
    drop proc sp_stop_profiler_trace
go

create proc sp_stop_profiler_trace @TraceID int = null
as

if @TraceID is not null
begin
    -- Set the trace status to stop
    exec sp_trace_setstatus @TraceID, 0

    -- Delete the trace
    exec sp_trace_setstatus @TraceID, 2
end
else
begin
-- the following cursor does not include the default trace
    declare c1 cursor for
    SELECT distinct traceid FROM :: fn_trace_getinfo (DEFAULT)
        WHERE traceId not in (select ID from sys.traces where is_default = 1)
    open c1
    fetch c1 into @TraceID
    while @@fetch_status = 0
    begin
        -- Set the trace status to stop
        exec sp_trace_setstatus @TraceID, 0

        -- Delete the trace
        exec sp_trace_setstatus @TraceID, 2
        fetch c1 into @TraceID
    end
    close c1
    deallocate c1
end